/**
 * @file hostchannel.h
 * @brief Decalares functions related to the host channel. This module is 
 *        responsible for communication between between the controller and the
 *        host (router/device).
 * @author Vamshi Ponnapalli
 */
#ifndef _WIZI_HOSTCHANNEL_H
  #define _WIZI_HOSTCHANNEL_H

  /*****************************************************************************
   * Includes
   ****************************************************************************/
  #include "hal_types.h"
  #include "hal_defs.h"
  #include "channel.h"

  /*************************************************************************
   * Fields (public)
   ************************************************************************/
  /**
   * A variable that represents the current state of the host channel. This is
   * designed for use in read only mode, and should never be written to from 
   * outside the host channel module.
   */
   extern uint16 hostchannel_State;

  /*****************************************************************************
   * Function declarations
   ****************************************************************************/
  /**
   * Initializes the host channel for communication. 
   * 
   * @return 0 if the operation was successful. A non zero error code otherwise.
   */
  uint8 hostchannel_initialize(void);

  /**
   * Sends a specific number of bytes to the host.
   * 
   * @param data A reference to the bytes that need to be sent to the host.
   * @param size The size of the data packet (in number of bytes) to be sent.
   * 
   * @return 0 if the operation was successful. A non zero error code otherwise.
   */
  uint8 hostchannel_sendData(uint8 *data, uint16 size);

  /**
   * Reads a specified number of bytes from the host.
   *
   * @param data A reference to the memory location that will store the received
   *             bytes.
   * @param size The number of bytes to read from the host.
   * 
   * @return 0 if the operation was successful. A non zero error code otherwise.
   */
  uint8 hostchannel_receiveData(uint8 *data, uint16 size);
    
  /**
   * Opens the host channel up for communication. The host channel uses the 
   * handler reference as a callback that is invoked when certain events 
   * (data received, connection opened, etc) occur.
   *
   * @param handler The callback routine that will be invoked on specific 
   *                hostchannel events occur.
   * @return 0 if the operation was successful. A non zero error code otherwise.
   */
  uint8 hostchannel_open(CHANNEL_EVENT_HANDLER handler);
  
  /**
   * Closes the host channel connection. The host channel will typically discard
   * any references it has to the callback handler as soon as this operation is
   * successfully completed.
   *
   * @return 0 if the operation was successful. A non zero error code otherwise.
   */
  uint8 hostchannel_close(void);
  
  /**
   * Checks if the receive buffer has any data in it (not yet processed), and 
   * returns the size of this data.
   *
   * @return The total number of bytes available to be read. 0 if there is no
   *         data to be read.
   */   
  uint16 hostchannel_getAvailableDataSize(void);
  
#endif
